<?php
/*
 * Copyright (C) 2010 TopCoder Inc., All Rights Reserved.
 */
namespace protocol\translation\framework\services\payment;

/**
 * <p>
 * The Payment Service OpenAPI RESTful implementation. The interface is defined based
 * on the One API specification.
 * </p>
 *
 * <p>
 * It has one method for each REST request type. Recess framework is used to map REST
 * requests to PHP methods making simple PHP methods REST aware.
 * </p>
 *
 * <p>
 * Thread Safety: Implementations are not required to be thread-safe.
 * </p>
 *
 * @author hpana, akinwale
 * @version 1.0
 */
interface Payment_Service {
    /**
     * <p>
     * Charges an amount to the end user's bill.
     * </p>
     *
     * <p.
     * The method will have the following Recess annotation.
     * Each annotation is bound directly to one method argument. Recess framework will automatically
     * bind these parameters extracted from the equest url, when a REST request is received to this
     * method annotated configuration url.
     * </p>
     *
     * @annotations:
     * @!Route POST, /$api_version/payment/$user_id/transactions/amount&carrier=$carrier
     *
     * @param string $api_version the API version
     * @param string $user_id the user ID
     * @param string $carrier the carrier to process the request
     *
     * @throws IllegalArgumentException if any argument is not of expected type or if it is not set or empty
     * @throws RequestProcessingException if any errors occur during processing
     */
    public function charge($api_version, $user_id, $carrier);

    /**
     * <p>
     * Reserves an amount for subsequent charging to an end user's bill.
     * </p>
     *
     * <p>
     * The method will have the following Recess annotation.
     * Each annotation is bound directly to one method argument. Recess framework will automatically
     * bind these parameters extracted from the equest url, when a REST request is received to this
     * method annotated configuration url.
     * </p>
     *
     * @annotations:
     * @!Route POST,  /$api_version/payment/payment/$user_id/transactions/amountReservation&carrier=$carrier
     *
     * @param string $api_version the API version
     * @param string $user_id the user ID
     * @param string $carrier the carrier to process the request
     *
     * @throws IllegalArgumentException if any argument is not of expected type or if it is not set or empty
     * @throws RequestProcessingException if any errors occur during processing
     */
    public function reserve($api_version, $user_id, $carrier);

    /**
     * <p>
     * Refunds the user for the payment.
     * </p>
     *
     * <p>
     * The method will have the following Recess annotation.
     * Each annotation is bound directly to one method argument. Recess framework will automatically
     * bind these parameters extracted from the equest url, when a REST request is received to this
     * method annotated configuration url.
     * </p>
     *
     * @annotations:
     * @!Route POST, /$api_version/smsmessaging/outbound/$sender_address/transactions/amount&carrier=$carrier
     *
     * @param string $api_version the API version
     * @param string $senderAddress the sender address
     * @param string $carrier the carrier to process the request
     *
     * @throws IllegalArgumentException if any argument is not of expected type or if it is not set or empty
     * @throws RequestProcessingException if any errors occur during processing
     */
    public function refundUser($api_version, $senderAddress, $carrier);

    /**
     * <p>
     * Verifies if initialization is successful and that class can execute business methods.
     * </p>
     *
     * <p>
     * Checks that $_converter and $_protocolClient are of appropriate type and initialized
     * and that $_converter is of type Diameter_JSON_Convertor.
     * </p>
     *
     * @throws InvalidStateException if the class is not initialized fully
     */
    public function checkInitialization();
}

?>